Core Methods

Get up and running with PyTure in minutes.

1. capture(**kwargs)

The capture method logs key–value pairs into the library, attaching a timestamp and a session ID automatically. This allows you to track user actions, API events, or any custom data in a structured way. Each call to capture appends the data both to a global capture list (_captures) and the instance buffer (self.buffer). The global capture list keeps a record of all captures during the program run, while the instance buffer can be used for session-specific operations, like saving or exporting later. This setup enables session-based logging: multiple captures build up a complete history of activity within a single session.

1. A unique session ID is generated automatically when the library is first imported.
2. Every capture automatically includes:

 - timestamp: ISO format of the capture time.
 - session_id: ID of the current session.
 - data: the user-provided key–value pairs.

3. If the library is in "dev" mode, it prints the captured data to the console for debugging

Example Usage:

python

from pyture import Pyture

# Initialize Pyture in dev mode to see live logs
p = Pyture(mode="dev")

# Capture some user actions
p.capture(action="login", user="Shakib")
p.capture(action="click_button", button_name="Start")


# Capture API response
p.capture(api="get_user_data", status="success", response_size=1024)

Console output in `dev` mode:

bash

[Captured] {'action': 'login', 'user': 'Shakib'}
[Captured] {'action': 'click_button', 'button_name': 'Start'}
[Captured] {'api': 'get_user_data', 'status': 'success', 'response_size': 1024}

Stored data in `_captures` (simplified view):

json

[
    {
        "timestamp": "2025-08-17T15:30:45.123456",
        "session_id": "a1b2c3d4-e5f6-7890-1234-56789abcdef0",
        "data": {"action": "login", "user": "Shakib"}
    },
    {
        "timestamp": "2025-08-17T15:31:00.654321",
        "session_id": "a1b2c3d4-e5f6-7890-1234-56789abcdef0",
        "data": {"action": "click_button", "button_name": "Start"}
    }
]

2. save(filename, mode="full")

The Save method writes all captured data to a JSON file, giving you flexible options on what to include:
- raw: only user-provided data.
- timestamp:timestamp + data.
- session: session ID + data.
- full: the complete object (timestamp + session ID + data). Default mode.

This lets users save exactly what they need for logging, debugging, or later analysis.

How it Works

1. Iterate through the global _captures list.
2. Depending on the mode, select which keys to include in the JSON.
3. Save the list of objects into the specified filename.
4. If the library is in "dev" mode, it prints a confirmation message.

Example Usage:

python

from pyture import Pyture

p = Pyture(mode="dev")

# Capture some events
p.capture(action="login", user="Shakib")
p.capture(action="click_button", button_name="Start")

# Save in different modes
p.save("captures_raw.json", mode="raw")
p.save("captures_timestamp.json", mode="timestamp")
p.save("captures_session.json", mode="session")
p.save("captures_full.json")  # defaults to 'full'

Captured data can be saved to a JSON file using save(). By default, it saves in full mode (timestamp + session ID + data).

python

pt.save("captures.json")

Example output (captures.json):

json

[
  {
    "timestamp": "2025-08-17T14:22:36.481902",
    "session_id": "8f2b1d43-3e21-4a8d-9132-52f4c8e2b7ab",
    "data": {
      "user": "alice",
      "action": "login"
    }
  },
  {
    "timestamp": "2025-08-17T14:23:01.792145",
    "session_id": "8f2b1d43-3e21-4a8d-9132-52f4c8e2b7ab",
    "data": {
      "user": "bob",
      "action": "logout"
    }
  }
]

JSON Previews for Each Mode:

1. raw

json

[
    {"action": "login", "user": "Shakib"},
    {"action": "click_button", "button_name": "Start"}
]

2. timestamp

json

[
    {"timestamp": "2025-08-17T15:30:45.123456", "data": {"action": "login", "user": "Shakib"}},
    {"timestamp": "2025-08-17T15:31:00.654321", "data": {"action": "click_button", "button_name": "Start"}}
]

3. session

json

[
    {"session_id": "a1b2c3d4-e5f6-7890-1234-56789abcdef0", "data": {"action": "login", "user": "Shakib"}},
    {"session_id": "a1b2c3d4-e5f6-7890-1234-56789abcdef0", "data": {"action": "click_button", "button_name": "Start"}}
]

4. full (default)

json

[
    {
        "timestamp": "2025-08-17T15:30:45.123456",
        "session_id": "a1b2c3d4-e5f6-7890-1234-56789abcdef0",
        "data": {"action": "login", "user": "Shakib"}
    },
    {
        "timestamp": "2025-08-17T15:31:00.654321",
        "session_id": "a1b2c3d4-e5f6-7890-1234-56789abcdef0",
        "data": {"action": "click_button", "button_name": "Start"}
    }
]

3. load(filename)

The load method loads previously saved JSON data back into the instance buffer. This allows you to resume a session or re-use captured data without starting from scratch.

- Only the instance buffer (self.buffer) is updated.

- The global _captures is not modified.

- If mode="dev", a confirmation message is printed.

How it Works:

1. Open the JSON file specified by filename.
2. Load the data into self.buffer.
3. Now, the buffer contains all previously saved captures (or just user data if saved in raw mode).

Example Usage:

python

from pyture import Pyture

p = Pyture(mode="dev")

# Load previously saved captures
p.load("captures_full.json")

# View buffer
print(p.buffer)

Console output (dev mode):

bash

[Loaded] Data loaded from 'captures_full.json'

Buffer content:

json

[
    {
        "timestamp": "2025-08-17T15:30:45.123456",
        "session_id": "a1b2c3d4-e5f6-7890-1234-56789abcdef0",
        "data": {"action": "login", "user": "Shakib"}
    }
]

4. clear():

The clear() function resets the current PyTure capture session. It removes all stored screenshots or captures from memory, allowing you to start fresh without saving the previous ones.

Syntax:

python

from pyture import PyTure

app = PyTure()
app.clear()

Example:

python

from pyture import PyTure

app = PyTure()

# Capture some screenshots
app.capture()
app.capture()

# Now clear everything
app.clear()

# At this point, memory is empty — no captures remain

Output:

bash

> python clear_example.py
Cleared: All captures have been removed.

Note: Use clear() when you want to reset captures without restarting your program.

5. get_session_info()

The get_session_info() function provides useful metadata about the current PyTure session. This includes details such as session ID, timestamp, active mode, and total captured items. It is particularly helpful for debugging, tracking, and monitoring workflows.

Example Usage:

python


from pyture import PyTure

session = PyTure()
session.capture("Example data")

info = session.get_session_info()
print(info)

output:

json


{
  "session_id": "e6a9d21b-3c74-4e21-9a8f-2dbf5f0d8c8f",
  "created_at": "2025-08-18 12:35:22",
  "mode": "full",
  "captured_items": 1
}

✅

Tip: Use this when you want to keep track of sessions or log important details automatically.

6. export_csv(filename)

The export_csv() function allows you to export all captured data into a CSV file, making it easy to analyze with tools like Excel, Google Sheets, or Pandas.

When exporting, PyCapture automatically flattens all keys into columns. This means that regardless of how many fields were captured (timestamps, session IDs, or custom user-defined fields), they will all be neatly arranged as columns in the CSV.

Syntax:

python


export_csv(filename)

Example Usage:

python


from pyture import PyTure

# Create a PyTure session
session = PyTure()

# Capture some data
session.capture(action="login", user="Alice")
session.capture(action="click", element="button", user="Alice")
session.capture(action="logout", user="Alice")

# Export all data into a CSV file
session.export_csv("captures.csv")

Preview: `captures.csv`

timestamp	session_id	action	user	element
2025-08-18T12:30:01.120000	e6a9d21b-3c74-4e21-9a8f-2dbf5f0d8c8f	login	Alice
2025-08-18T12:32:45.420000	e6a9d21b-3c74-4e21-9a8f-2dbf5f0d8c8f	click	Alice	button
2025-08-18T12:35:10.880000	e6a9d21b-3c74-4e21-9a8f-2dbf5f0d8c8f	logout	Alice

Columns are flattened automatically: built-ins (timestamp, session_id) + your custom keys.

✅

Success! You've created your first PyTure capture and saved it to JSON. Your data is now safely stored and ready for analysis.

Core Methods

1. capture(**kwargs)

Example Usage:

Console output in dev mode:

Stored data in _captures (simplified view):

2. save(filename, mode="full")

How it Works

Example Usage:

JSON Previews for Each Mode:

1. raw

2. timestamp

3. session

4. full (default)

3. load(filename)

How it Works:

Example Usage:

Console output (dev mode):

Buffer content:

4. clear():

Syntax:

Example:

Output:

5. get_session_info()

Example Usage:

output:

6. export_csv(filename)

Syntax:

Example Usage:

Preview: captures.csv

Console output in `dev` mode:

Stored data in `_captures` (simplified view):

Preview: `captures.csv`